home *** CD-ROM | disk | FTP | other *** search
/ MASPC 1 / MASPC_1.iso / Demos / Demo DIV / DATA / DLL / SOURCE / LEEME.TXT < prev    next >
Encoding:
Text File  |  1997-11-24  |  8.2 KB  |  208 lines
  1.  
  2. DIV Games Studio - Dinamic Link Libraries
  3. ───────────────────────────────────────────────────────────────────────────────
  4.  
  5. Este documento presenta la información necesaria para construir DLL para DIV.
  6.  
  7. - ¿Qué es una DLL?
  8.  
  9.   Una DLL (librería de enlace dinámico), es una parte de un programa que puede
  10. fusionarse con otro programa en tiempo de ejecución, y que contiene funciones
  11. o procedimientos que serán utilizados por el programa.
  12.  
  13. - ¿Para que sirven?
  14.  
  15.   Las DLL sirven para extender el lenguaje de programación DIV o para modificar
  16. parcialmente su funcionamiento. Estas permiten implementar partes de un
  17. programa en lenguaje C, para después llamarlas desde el propio DIV.
  18.  
  19. - ¿Que tipos hay?
  20.  
  21.   Hay básicamente tres tipos de DLL que pueden construirse para DIV, las
  22. primeras son los salvapantallas, las segundas las de autocarga y las terceras
  23. las que añaden nuevas funciones al lenguaje.
  24.  
  25. Instrucciones generales.
  26. ───────────────────────────────────────────────────────────────────────────────
  27.  
  28. Este es un procedimiento asequible únicamente para programadores EXPERTOS en C,
  29. que dispongan del "WATCOM C++ Compiler", es probable que se puedan utilizar
  30. para esto otros compiladores de C, pero nosotros no hemos hecho pruebas con
  31. ellos y, por lo tanto, no podemos asegurar que vayan a funcionar.
  32.  
  33. Lo primero debe ser añadir el siguiente texto al fichero WLSYSTEM.LNK de Watcom
  34. (que está en el directorio BINB\ de este compilador).
  35.  
  36. system begin div_dll
  37.     option osname='DIV DLL'
  38.     libpath %WATCOM%\lib386
  39.     libpath %WATCOM%\lib386\dos
  40.     format windows nt dll ^
  41. end
  42.  
  43. El formato de código empleado es el de las DLL de Windows NT, y esta es la
  44. forma de indicarle a Watcom que genere este tipo de código.
  45.  
  46. Después se debe incluir el fichero de cabecera DIV.H, que también viene en este
  47. directorio, en él se describen las variables y funciones básicas sobre las que
  48. se puede interactuar. Además este fichero contiene una serie de "#define" para
  49. facilitar el acceso a las variables internas de DIV32RUN, que es el módulo que
  50. contiene todas las funciones y rutinas internas de DIV Games Studio.
  51.  
  52. Se incluyen varios ejemplos, los mas básicos son estos tres:
  53.  
  54.   DEMO0.CPP - Ejemplo básico de un salvapantallas para los juegos DIV.
  55.   DEMO1.CPP - Ejemplo básico de una DLL de autocarga.
  56.   DEMO2.CPP - Ejemplo básico de una DLL de funciones.
  57.  
  58. Se puede utilizar el archivo de proceso por lotes denominado MAKE.BAT para
  59. compilar estas DLL (si se dispone del Watcom C++ para DOS) que, si no se
  60. produce ningún error, generará la DLL correspondiente (con el mismo nombre).
  61.  
  62. Normas básicas.
  63. ───────────────────────────────────────────────────────────────────────────────
  64.  
  65. Las DLL se deben crear en lenguaje C estándar y cuentan con algunas normas
  66. que deben ser respetadas, por ejemplo:
  67.  
  68. - Se debe incluir la cabecera "div.h", y en el módulo principal, se debe
  69. realizar la siguiente definición:
  70.  
  71.   #define GLOBALS
  72.  
  73.   antes de incluir esta cabecera (antes del #include "div.h"), para que se
  74. definan las variables, tipos y estructuras básicas el dicho módulo (esto es
  75. para cuando se construyan DLL formadas por varios fuentes CPP).
  76.  
  77. - No es posible utilizar en las mismas las funciones malloc(), free(), fopen()
  78. o fclose(), debiéndose utilizar en su lugar div_malloc(), div_free(),
  79. div_fopen() y div_fclose(). Estas funciones se comportan exactamente igual que
  80. sus homónimas de C.
  81.  
  82. - Deben definirse siempre dos funciones, de inicialización y finalización de
  83. la DLL, estas son:
  84.  
  85.   void __export divmain(COMMON_PARAMS) {
  86.     GLOBAL_IMPORT();
  87.     // Inicialización
  88.   }
  89.  
  90.   void __export divend(COMMON_PARAMS) {
  91.     // Finalización
  92.   }
  93.  
  94. - Al margen de las funciones exportadas por DIV, pueden utilizarse la mayoría
  95. de funciones estándar de C, incluyendo sus cabeceras correspondientes (sus .h).
  96.  
  97. ¿Como se utilizan las DLL en el lenguaje?
  98. ───────────────────────────────────────────────────────────────────────────────
  99.  
  100. Las DLL se dividen en dos tipos: las normales y las de autocarga.
  101.  
  102. Para utilizar las normales, se debe indicar en los juegos una sentencia:
  103.  
  104.   IMPORT "directorio\nombre.dll";
  105.  
  106. Justo tras las declaraciones LOCAL del programa principal. No se pueden
  107. utilizar DLL de otros lenguajes.
  108.  
  109. Las de autocarga pueden utilizarse de la misma forma, o bien simplemente
  110. copiándolas al directorio del juego. Se activarán automáticamente.
  111.  
  112. Por ejemplo, si se copia DEMO0.DLL (el salvapantallas ejemplo) en el directorio
  113. de un juego hecho en DIV, este se activará automáticamente cada vez que se
  114. ejecute el juego. Para que se activen estas DLL cuando se ejecuta un juego
  115. desde el entorno de DIV, se deben copiar al directorio donde se encuentra
  116. el fichero D.EXE (el ejecutable principal de DIV).
  117.  
  118. Salva-pantallas (ver demo0.cpp)
  119. ───────────────────────────────────────────────────────────────────────────────
  120.  
  121. Se pueden definir las siguientes funciones en la DLL.
  122.  
  123.   ss_init() - para inicializar el salvapantallas (cada vez que salte).
  124.  
  125.   ss_frame() - para realizar operaciones sobre el buffer de vídeo, antes de
  126.   cada volcado.
  127.  
  128.   ss_end() - para finalizar el salvapantallas.
  129.  
  130. Se dispone además de las siguientes variables:
  131.  
  132.   ss_time - para indicar cada cuanto tiempo debe saltar el salvapantallas,
  133.   en centésimas de segundo (por defecto vale 3000, es decir, cada 30 segundos).
  134.  
  135.   ss_status - para activar y desactivar el salvapantallas (0-Desactivo/1-Activo).
  136.  
  137.   ss_exit - se debe poner a 1 en ss_frame() para finalizar forzosamente el
  138.   salvapantallas (el sistema la pondrá a 1 cuando se active el teclado, el
  139.   ratón o el joystick).
  140.  
  141. Se incluye en SS1.CPP un salvapantallas algo más elaborado que el de DEMO0.CPP,
  142. este simula que la pantalla se funde como si se tratara de un cuadro de granos
  143. de arena.
  144.  
  145. DLL de autocarga (ver demo1.cpp)
  146. ───────────────────────────────────────────────────────────────────────────────
  147.  
  148.   Estas son DLL que suelen sustituir algunas de las funciones internas de DIV
  149. por otras, las funciones que se pueden definir están explicadas en DIV.H
  150. (bajo la cabecera "DIV standard Entry-Points").
  151.  
  152.   Para que una DLL se auto-cargue, se debe incluir la siguiente sentencia
  153. dentro de la función div_main():
  154.  
  155.   Autoload();
  156.  
  157.   Se incluyen dos DLL de autocarga a modo de ejemplo:
  158.  
  159.   AGUA.CPP - Simula el efecto de agua en la parte inferior de la pantalla.
  160.  
  161.   HBOY.CPP - ¡Pruébala con cualquier juego DIV! ... ya verás.
  162.  
  163. DLL de funciones (ver demo2.cpp)
  164. ───────────────────────────────────────────────────────────────────────────────
  165.  
  166.   Es fácil añadir nuevas funciones al lenguaje:
  167.  
  168.   Primero, se debe crear la nueva función en la DLL, esta debe leer sus
  169. parámetros de llamada con getparm() (que devuelve siempre un int), y al
  170. finalizar se debe SIEMPRE retornar un valor con retval() (ver demo2.cpp).
  171.  
  172.   Después se debe definir en la DLL la función:
  173.  
  174.   void __export divlibrary(LIBRARY_PARAMS) {
  175.   }
  176.  
  177.   y dentro de la misma se debe hacer una llamada a COM_export() por cada
  178. función que se añada al lenguaje.
  179.  
  180.   COM_export() recibe tres parámetros, el primero es el nombre que tendrá
  181. la función en el lenguaje, el segundo el puntero a la misma, y el tercero el
  182. número de parámetros de llamada.
  183.  
  184.   En los programas creados en DIV, tras hacer el IMPORT de la DLL, se podrán
  185. utilizar directamente estas funciones.
  186.  
  187. ¿Que se puede hacer?
  188. ───────────────────────────────────────────────────────────────────────────────
  189.  
  190. Explorando DIV.H encontrarás muchas cosas a las que se puede acceder en las
  191. DLL, se pueden hacer programas que modifiquen las variables de los procesos,
  192. que sustituyan las rutinas de vídeo, que apliquen efectos en ventanas, etc.
  193.  
  194. Si consigues crear una DLL funcional, no se pone ningún pero a que la
  195. distribuyas como Shareware o como quieras, y si la creas como Freeware ...
  196. ¡pues mejor!.
  197.  
  198. En cualquier caso, te agradecería que me informaras, a través de HAMMER o de la
  199. página WEB de DIV Games Studio de tus logros personales :-)
  200.  
  201. También agradeceré cualquier sugerencia sobre DIV Games Studio, y si son
  202. realmente prácticas y originales, mejor (no te molestes en pedir funciones
  203. para módulos de sonido, para 3d, true color ... ¡ya estamos en ello!).
  204.  
  205.             ¡Gracias por intentarlo!
  206.  
  207.             Daniel Navarro Medrano, programador principal de DIV Games Studio.
  208.